feat(docs): document Resource Mapping Groups and FQN format by marythought · Pull Request #350 · opentdf/docs

marythought · 2026-06-22T20:17:23Z

Summary

Add Resource Mapping Groups section to the resource_mappings page
Document the FQN format (https://<namespace>/resm/<group-name>)
Show CLI usage for creating groups and assigning mappings
Explain usage of group FQNs as synonym dictionary identifiers

This gap was identified when the FQN format could not be found in any documentation or CLI output, requiring engineers to read source code to discover it.

Test plan

npm run build passes
Surge preview renders the updated page correctly
Content reviewed for accuracy against source code (lib/identifier/resource_mapping_group.go)

🤖 Generated with Claude Code

Summary by CodeRabbit

Documentation
- Expanded the Resource Mappings guide to document the optional group field and improved the structure of the “Examples” section.
- Added a “Resource Mapping Groups” section describing group composition and the required group FQN format (including lowercase normalization) and URL pattern.
- Included CLI instructions to create groups and assign mappings, with notes on current behavior when listing/getting groups.
- Explained how groups can be used as synonym dictionaries for database-backed FQN resolution.

coderabbitai · 2026-06-22T20:17:39Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: f4087a58-eef2-4cb4-bbad-d9bfb4bbfa70

📥 Commits

Reviewing files that changed from the base of the PR and between bf0b8c4 and dc70f80.

📒 Files selected for processing (1)

docs/components/policy/resource_mappings.md

🚧 Files skipped from review as they are similar to previous changes (1)

docs/components/policy/resource_mappings.md

📝 Walkthrough

Walkthrough

Documentation for resource_mappings.md is updated to add an optional group field, reformat the Examples section, and introduce Resource Mapping Groups with FQN format, CLI workflow, and synonym dictionary lookup guidance.

Changes

Resource Mapping Groups Docs

Layer / File(s)	Summary
Mapping field and examples `docs/components/policy/resource_mappings.md`	Adds the optional `group` field to the resource mapping description and makes “Examples” an explicit level-2 section.
Resource Mapping Groups `docs/components/policy/resource_mappings.md`	Adds group composition, FQN construction and normalization, the `otdfctl` visibility note, CLI commands for creating groups and assigning mappings, and synonym dictionary lookup text.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

A rabbit hops through policy land,
With groups and FQNs close at hand.
Examples now have a tidy light,
And synonym paths feel clear and right. 🐇

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main documentation change: adding Resource Mapping Groups and the FQN format to the resource mappings docs.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch mary/DSPX-3656-resource-mapping-groups-docs

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

gemini-code-assist

Code Review

This pull request updates the documentation for Resource Mappings to introduce Resource Mapping Groups, explaining their purpose, FQN format, CLI commands for creation, and usage as synonym dictionaries. It also fixes a minor typo in an example URL. The reviewer suggested using the .md extension for relative file links to ensure build-time validation in Docusaurus and compatibility with standard Markdown readers.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

github-actions · 2026-06-22T20:19:02Z

❌ Surge preview build failed — no preview was deployed. Check the workflow logs for details.

Once the build passes, the preview will be at: https://opentdf-docs-pr-350.surge.sh

Common cause: If the build failed on vendored YAML validation, run the following locally and commit the result:

npm run update-vendored-yaml
git add specs/
git commit -m "chore(deps): update vendored OpenAPI specs"

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/components/policy/resource_mappings.md`:
- Line 33: Add language specifiers to the fenced code blocks to comply with the
MD040 linting rule. Locate the two code blocks containing the FQN examples (at
the lines with the namespace/resm examples) and change the opening triple
backticks from ``` to ```text for both blocks to provide proper syntax
highlighting and satisfy the linting requirement.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: c09b1cf2-2226-495e-a860-ddeb169196a8

📥 Commits

Reviewing files that changed from the base of the PR and between 12fcee6 and 845401f.

📒 Files selected for processing (1)

docs/components/policy/resource_mappings.md

Add Resource Mapping Groups section to the resource_mappings page covering group composition, FQN format (https://<namespace>/resm/<name>), CLI usage for creating groups and assigning mappings, and usage as synonym dictionaries. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Address Gemini and CodeRabbit review feedback: - Use ./attributes.md#namespaces for build-time link validation - Add text language specifier to FQN code blocks (MD040) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

github-actions · 2026-06-23T14:42:33Z

📄 Preview deployed to https://opentdf-docs-pr-350.surge.sh

Tie the CLI example to Bob's DoD classification scenario from earlier in the page instead of using generic placeholders. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

marythought requested review from a team as code owners June 22, 2026 20:17

gemini-code-assist Bot reviewed Jun 22, 2026

View reviewed changes

Comment thread docs/components/policy/resource_mappings.md Outdated

coderabbitai Bot reviewed Jun 22, 2026

View reviewed changes

Comment thread docs/components/policy/resource_mappings.md Outdated

marythought and others added 2 commits June 22, 2026 16:14

marythought force-pushed the mary/DSPX-3656-resource-mapping-groups-docs branch from 845401f to 0faf858 Compare June 22, 2026 23:15

marythought and others added 3 commits June 23, 2026 07:57

chore: trigger surge preview rebuild

ecc45fb

fix(docs): use classification example in CLI snippet

bf0b8c4

Tie the CLI example to Bob's DoD classification scenario from earlier in the page instead of using generic placeholders. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fix(docs): rename examples to Alex and Beth, fix pronouns

056bde4

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

marythought enabled auto-merge (squash) June 23, 2026 16:00

Merge branch 'main' into mary/DSPX-3656-resource-mapping-groups-docs

dc70f80

elizabethhealy approved these changes Jun 25, 2026

View reviewed changes

marythought merged commit f08112f into main Jun 25, 2026
8 checks passed

marythought deleted the mary/DSPX-3656-resource-mapping-groups-docs branch June 25, 2026 13:37

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(docs): document Resource Mapping Groups and FQN format#350

feat(docs): document Resource Mapping Groups and FQN format#350
marythought merged 6 commits into
mainfrom
mary/DSPX-3656-resource-mapping-groups-docs

marythought commented Jun 22, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jun 22, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Poem

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

Uh oh!

github-actions Bot commented Jun 22, 2026

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

github-actions Bot commented Jun 23, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

marythought commented Jun 22, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jun 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Poem

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

github-actions Bot commented Jun 22, 2026

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions Bot commented Jun 23, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

marythought commented Jun 22, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jun 22, 2026 •

edited

Loading